<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: &lt;code&gt;Android.mk&lt;/code&gt;</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__building__chapter_1-section_8__android_8mk.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title"><code>Android.mk</code> </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="#intro">Introduction</a><br/>
 <a href="#over">Overview</a><br/>
 <a href="#se">Simple example</a><br/>
 <a href="#reference">Reference</a><br/>
 <a href="#npv">NDK-provided variables</a><br/>
 <a href="#npfm">NDK-provided function macros</a><br/>
 <a href="#mdv">Module-description variables</a><br/>
</p>
<p><a class="anchor" id="intro"></a> </p>
<h2>Introduction</h2>
<p>This section describes the syntax of <code>Android.mk</code> build file,
which describes your C and C++ source files to the Android NDK.</p>
<p><a class="anchor" id="over"></a> </p>
<h2>Overview</h2>
<p>The <code>Android.mk</code> file describes your sources to the build system.
More specifically:</p>
<ul>
<li>The file is really a tiny GNU Makefile fragment that the build system
parses once or more. As such, you should try to minimize the variables you
declare there. Also, do not assume that anything is not defined during
parsing.</li>
<li>The file syntax is designed to allow you to group your sources into
“modules”. A module is one of the following:<ul>
<li>A static library.</li>
<li>A shared library.</li>
<li>A standalone executable.</li>
</ul>
</li>
</ul>
<p>The build system only installs/copies shared libraries into your application
package. In addition, static libraries can generate shared libraries.</p>
<p>You can define one or more modules in each <code>Android.mk</code> file, and
you can use the same source file in multiple modules.</p>
<ul>
<li>The build system handles many details for you. For example, you don't need
to list header files or explicit dependencies between generated files in your
<code>Android.mk</code>. The NDK build system computes these automatically for
you.</li>
</ul>
<p>This also means that, when updating to newer releases of the NDK, you should
be able to benefit from new toolchain/platform support without having to touch
your <code>Android.mk</code> files.</p>
<p>Note that the syntax is <em>very</em> close to the one used in
<code>Android.mk</code> files distributed with the full <a
href="https://source.android.com">Android Open Source Project</a>. While the
build system implementation that uses them is different, their similarity is an
intentional design decision aimed at making it easier for application
developers to reuse source code for “external” libraries.</p>
<p><a class="anchor" id="se"></a> </p>
<h2>Simple example</h2>
<p>Before describing the syntax in detail, it is useful to consider the
Android.mk used in the Hello-JNI sample.</p>
<p>The <code>jni/Android.mk</code> file describes the shared library to the NDK
build system. Its content is: </p>
<pre class="fragment">    ---------- cut here ------------------
    LOCAL_PATH := $(call my-dir)

    include $(CLEAR_VARS)

    LOCAL_MODULE    := hello-jni
    LOCAL_SRC_FILES := hello-jni.c

    include $(BUILD_SHARED_LIBRARY)
    ---------- cut here ------------------
</pre><p>Now, let's explain these lines: </p>
<pre class="fragment">    LOCAL_PATH := $(call my-dir)
</pre><p>An <code>Android.mk</code> file must begin with the definition of the
LOCAL_PATH variable. It is used to locate source files in the development tree.
In this example, the macro function 'my-dir', provided by the build system, is
used to return the path of the current directory (i.e. the directory containing
the <code>Android.mk</code> file itself). </p>
<pre class="fragment">    include $(CLEAR_VARS)
</pre><p>The CLEAR_VARS variable is provided by the build system and points to
a special GNU Makefile that will clear many LOCAL_XXX variables for you (e.g.
LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...), with the
exception of LOCAL_PATH. This is needed because all build control files are
parsed in a single GNU Make execution context where all variables are global.
</p>
<pre class="fragment">    LOCAL_MODULE := hello-jni
</pre><p>The LOCAL_MODULE variable must be defined to identify each module you
describe in your <code>Android.mk</code>. The name must be <em>unique</em> and
not contain any spaces. Note that the build system will automatically add
proper prefix and suffix to the corresponding generated file. In other words, a
shared library module named 'foo' will generate 'libfoo.so'.</p>
<p>IMPORTANT NOTE: If you name your module 'libfoo', the build system will not
add another 'lib' prefix and will generate libfoo.so as well. This is to
support <code>Android.mk</code> files that originate from the Android platform
sources, would you need to use these. </p>
<pre class="fragment">    LOCAL_SRC_FILES := hello-jni.c
</pre><p>The LOCAL_SRC_FILES variables must contain a list of C and/or C++
source files that will be built and assembled into a module. Note that you
should not list header and included files here, because the build system will
compute dependencies automatically for you; just list the source files that
will be passed directly to a compiler, and you should be good.</p>
<p>Note that the default extension for C++ source files is '.cpp'. It is
however possible to specify a different one by defining the variable
LOCAL_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' will work, but
not 'cxx'). </p>
<pre class="fragment">    include $(BUILD_SHARED_LIBRARY)
</pre><p>The BUILD_SHARED_LIBRARY is a variable provided by the build system
that points to a GNU Makefile script that is in charge of collecting all the
information you defined in LOCAL_XXX variables since the latest 'include ' and
determine what to build, and how to do it exactly. There is also
BUILD_STATIC_LIBRARY to generate a static library.</p>
<p>There are more complex examples in the samples directories, with commented
<code>Android.mk</code> files that you can look at.</p>
<p><a class="anchor" id="reference"></a> </p>
<h2>Reference</h2>
<p>This is the list of variables you should either rely on or define in an
<code>Android.mk</code>. You can define other variables for your own usage, but
the NDK build system reserves the following variable names:</p>
<ul>
<li>Names that begin with LOCAL_ (e.g. LOCAL_MODULE)</li>
<li>Names that begin with PRIVATE_, NDK_ or APP_ (used internally)</li>
<li>Lower-case names (used internally, e.g. <code>my-dir</code>)</li>
</ul>
<p>If you need to define your own convenience variables in an
<code>Android.mk</code> file, we recommend using the MY_ prefix, for a trivial
example: </p>
<pre class="fragment">    ---------- cut here ------------------
    MY_SOURCES := foo.c
    ifneq ($(MY_CONFIG_BAR),)
      MY_SOURCES += bar.c
    endif

    LOCAL_SRC_FILES += $(MY_SOURCES)
    ---------- cut here ------------------
</pre><p>So, here we go:</p>
<p><a class="anchor" id="npv"></a> </p>
<h2>NDK-provided variables</h2>
<p>These GNU Make variables are defined by the build system before your
<code>Android.mk</code> file is parsed. Note that under certain circumstances
the NDK might parse your <code>Android.mk</code> several times, each with
different definition for some of these variables.</p>
<h3><code>CLEAR_VARS</code></h3>
<p>Points to a build script that undefines nearly all LOCAL_XXX variables
listed in the "Module-description" section below. You must include the script
before starting a new module, e.g.: </p>
<pre class="fragment">        include $(CLEAR_VARS)
</pre><h3><code>BUILD_SHARED_LIBRARY</code></h3>
<p>Points to a build script that collects all the information about the module
you provided in LOCAL_XXX variables and determines how to build a target shared
library from the sources you listed. Note that you must have LOCAL_MODULE and
LOCAL_SRC_FILES defined, at a minimum before including this file. Example
usage: </p>
<pre class="fragment">        include $(BUILD_SHARED_LIBRARY)
</pre><p>note that this will generate a file named <code>lib.so</code>.</p>
<h3><code>BUILD_STATIC_LIBRARY</code></h3>
<p>A variant of BUILD_SHARED_LIBRARY that is used to build a target static
library instead. Static libraries are not copied into your project/packages but
can be used to build shared libraries (see LOCAL_STATIC_LIBRARIES and
LOCAL_WHOLE_STATIC_LIBRARIES described below). Example usage: </p>
<pre class="fragment">        include $(BUILD_STATIC_LIBRARY)
</pre><p>Note that this will generate a file named <code>lib.a</code>.</p>
<h3><code>PREBUILT_SHARED_LIBRARY</code></h3>
<p>Points to a build script used to specify a prebuilt shared library. Unlike
BUILD_SHARED_LIBRARY and BUILD_STATIC_LIBRARY, the value of LOCAL_SRC_FILES
must be a single path to a prebuilt shared library (e.g.
<code>foo/libfoo.so</code>), instead of a source file.</p>
<p>You can reference the prebuilt library in another module using the
LOCAL_PREBUILTS variable (see <a
href="md_3__key__topics__libraries__p_r_e_b_u_i_l_t_s.html">NDK Prebuilt
Library Support</a> for more information).</p>
<h3><code>PREBUILT_STATIC_LIBRARY</code></h3>
<p>This is the same as PREBUILT_SHARED_LIBRARY, but for a static library file
instead. See <a href="md_3__key__topics__libraries__p_r_e_b_u_i_l_t_s.html">NDK
Prebuilt library support</a> for more.</p>
<h3><code>TARGET_ARCH</code></h3>
<p>Name of the target CPU architecture as it is specified by the Android Open
Source Project. This is <code>arm</code> for any ARM-compatible build,
independent of the CPU architecture revision.</p>
<h3><code>TARGET_PLATFORM</code></h3>
<p>Name of the target Android platform when this <code>Android.mk</code> is
parsed. For example, <code>android-3</code> corresponds to Android 1.5 system
images. For a complete list of platform names and corresponding Android system
images, read <a
href="md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Android NDK
Stable APIs</a>.</p>
<h3><code>TARGET_ARCH_ABI</code></h3>
<p>Name of the target CPU+ABI when this <code>Android.mk</code> is parsed. You
can specify one or more of the following values: </p>
<pre class="fragment">   armeabi
        For ARMv5TE

   armeabi-v7a
        For ARMv7

   arm64-v8a
        For ARMv8 AArch64

   x86
        For i686

   x86_64
        For x86-64

   mips
        For mips32 (r1)

   mips64
        For mips64 (r6)
</pre><p>NOTE: Up to Android NDK 1.6_r1, this variable was simply defined as
'<code>arm</code>'. However, the value has been redefined to better match what
is used internally by the Android platform.</p>
<p>For more details about architecture ABIs and corresponding compatibility
issues, please read <a
href="./md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">And
roid Native CPU ABI Management</a></p>
<p>Other target ABIs will be introduced in future releases of the NDK and will
have a different name. Note that all ARM-based ABIs will have 'TARGET_ARCH'
defined to '<code>arm</code>', but may have different 'TARGET_ARCH_ABI'</p>
<h3><code>TARGET_ABI</code></h3>
<p>The concatenation of target platform and ABI, it really is defined as
<code>-</code> and is useful when you want to test against a specific target
system image for a real device.</p>
<p>By default, this will be '<code>android-3-armeabi</code>'</p>
<p>(Up to Android NDK 1.6_r1, this used to be '<code>android-3-arm</code>' by
default)</p>
<p><a class="anchor" id="npfm"></a> </p>
<h2>NDK-provided function macros</h2>
<p>The following are GNU Make 'function' macros, and must be evaluated by using
'$(call &lt;function&gt;)'. They return textual information.</p>
<h3><code>my-dir</code></h3>
<p>Returns the path of the last included Makefile, which typically is the
current <code>Android.mk</code>'s directory. This is useful to define
LOCAL_PATH at the start of your <code>Android.mk</code> as with: </p>
<pre class="fragment">          LOCAL_PATH := $(call my-dir)
</pre><p>IMPORTANT NOTE: Due to the way GNU Make works, this really returns the
path of the <em>last</em> <em>included</em> <em>Makefile</em> during the
parsing of build scripts. Do not call <code>my-dir</code> after including
another file.</p>
<p>For example, consider the following example: </p>
<pre class="fragment">          LOCAL_PATH := $(call my-dir)

          ... declare one module

          include $(LOCAL_PATH)/foo/`Android.mk`

          LOCAL_PATH := $(call my-dir)

          ... declare another module
</pre><p>The problem here is that the second call to <code>my-dir</code> will
define LOCAL_PATH to <code>$PATH/foo</code> instead of <code>$PATH</code>, due
to the include that was performed before that.</p>
<p>For this reason, it's better to put additional includes after everything
else in an <code>Android.mk</code>, as in: </p>
<pre class="fragment">          LOCAL_PATH := $(call my-dir)

          ... declare one module

          LOCAL_PATH := $(call my-dir)

          ... declare another module

          # extra includes at the end of the `Android.mk`
          include $(LOCAL_PATH)/foo/`Android.mk`
</pre><p>If this is not convenient, save the value of the first
<code>my-dir</code> call into another variable, for example: </p>
<pre class="fragment">          MY_LOCAL_PATH := $(call my-dir)

          LOCAL_PATH := $(MY_LOCAL_PATH)

          ... declare one module

          include $(LOCAL_PATH)/foo/`Android.mk`

          LOCAL_PATH := $(MY_LOCAL_PATH)

          ... declare another module
</pre><h3><code>all-subdir-makefiles</code></h3>
<p>Returns a list of <code>Android.mk</code> located in all sub-directories of
the current 'my-dir' path. For example, consider the following hierarchy: </p>
<pre class="fragment">          sources/foo/Android.mk
          sources/foo/lib1/Android.mk
          sources/foo/lib2/Android.mk
</pre><p>If sources/foo/<code>Android.mk</code> contains the single line: </p>
<pre class="fragment">          include $(call all-subdir-makefiles)
</pre><p>Then it will include automatically
sources/foo/lib1/<code>Android.mk</code> and
sources/foo/lib2/<code>Android.mk</code></p>
<p>This function can be used to provide deep-nested source directory
hierarchies to the build system. Note that by default, the NDK will only look
for files in sources/*/<code>Android.mk</code></p>
<h3><code>this-makefile</code></h3>
<p>Returns the path of the current Makefile (i.e. where the function is
called).</p>
<h3><code>parent-makefile</code></h3>
<p>Returns the path of the parent Makefile in the inclusion tree, i.e. the path
of the Makefile that included the current one.</p>
<h3><code>grand-parent-makefile</code></h3>
<p>Guess what...</p>
<h3><code>import-module</code></h3>
<p>A function that allows you to find and include the <code>Android.mk</code>
of another module by name. A typical example is: </p>
<pre class="fragment">        $(call import-module,&lt;name&gt;)
</pre><p>And this will look for the module tagged &lt;name&gt; in the list of
directories referenced by your NDK_MODULE_PATH environment variable, and
include its <code>Android.mk</code> automatically for you.</p>
<p>Read <a href="md_4__additional__info__i_m_p_o_r_t-_m_o_d_u_l_e.html">Andoid
Module Paths (Sharing Code Made Easy)</a> for more details.</p>
<p><a class="anchor" id="mdv"></a> </p>
<h2>Module-description variables</h2>
<p>The following variables are used to describe your module to the build
system. You should define some of them between an '<code>include </code>' and
an '<code>include </code>'. As written previously,  is a script that will
undefine/clear all of these variables, unless explicitly noted in their
description.</p>
<h3><code>LOCAL_PATH</code></h3>
<p>This variable is used to give the path of the current file. You MUST define
it at the start of your <code>Android.mk</code>, which can be done with: </p>
<pre class="fragment">        LOCAL_PATH := $(call my-dir)
</pre><p>This variable is <em>not</em> cleared by  so only one definition per
<code>Android.mk</code> is needed (in case you define several modules in a
single file).</p>
<h3><code>LOCAL_MODULE</code></h3>
<p>This is the name of your module. It must be unique among all module names,
and shall not contain any space. You MUST define it before including any
script.</p>
<p>By default, the module name determines the name of generated files, e.g.
lib&lt;foo&gt;.so for a shared library module named &lt;foo&gt;. However you
should only refer to other modules with their 'normal' name (e.g. &lt;foo&gt;)
in your NDK build files (either <code>Android.mk</code> or Application.mk)</p>
<p>You can override this default with LOCAL_MODULE_FILENAME (see below)</p>
<h3><code>LOCAL_MODULE_FILENAME</code></h3>
<p>This variable is optional, and allows you to redefine the name of generated
files. By default, module &lt;foo&gt; will always generate a static library
named lib&lt;foo&gt;.a or a shared library named lib&lt;foo&gt;.so, which are
standard Unix conventions.</p>
<p>You can override this by defining LOCAL_MODULE_FILENAME, For example: </p>
<pre class="fragment">          LOCAL_MODULE := foo-version-1
          LOCAL_MODULE_FILENAME := libfoo
</pre><p>*NOTE(: You should not put a path or file extension in your
LOCAL_MODULE_FILENAME, these will be handled automatically by the build
system.</p>
<h3><code>LOCAL_SRC_FILES</code></h3>
<p>This is a list of source files that will be built for your module. Only list
the files that will be passed to a compiler, since the build system
automatically computes dependencies for you.</p>
<p>Note that source files names are relative to LOCAL_PATH and you can use path
components, e.g.: </p>
<pre class="fragment">        LOCAL_SRC_FILES := foo.c \
                           toto/bar.c
</pre><p>Absolute file paths are also supported: </p>
<pre class="fragment">        LOCAL_SRC_FILES := /home/user/mysources/foo.c
</pre><p>or on Windows: </p>
<pre class="fragment">        LOCAL_SRC_FILES := c:/Users/user/sources/foo.c
</pre><p>Avoiding absolute file paths is recommended, this makes your
<code>Android.mk</code> easy to reuse on a different machine / system.</p>
<p>NOTE: Always use Unix-style forward slashes (/) in build files.
Windows-style back-slashes will not be handled properly.</p>
<h3><code>LOCAL_CPP_EXTENSION</code></h3>
<p>This is an optional variable that can be defined to indicate the file
extension(s) of C++ source files. They must begin with a dot. The default is
'.cpp' but you can change it. For example: </p>
<pre class="fragment">          LOCAL_CPP_EXTENSION := .cxx
</pre><p>Since NDK r7, you can list several extensions in this variable, as in:
</p>
<pre class="fragment">          LOCAL_CPP_EXTENSION := .cxx .cpp .cc
</pre><h3><code>LOCAL_CPP_FEATURES</code></h3>
<p>This is an optional variable that can be defined to indicate that your code
relies on specific C++ features. To indicate that your code uses RTTI (RunTime
Type Information), use the following: </p>
<pre class="fragment">          LOCAL_CPP_FEATURES := rtti
</pre><p>To indicate that your code uses C++ exceptions, use: </p>
<pre class="fragment">          LOCAL_CPP_FEATURES := exceptions
</pre><p>You can also use both of them with (order is not important): </p>
<pre class="fragment">          LOCAL_CPP_FEATURES := rtti features
</pre><p>The effect of this variable is to enable the right compiler/linker
flags when building your modules from sources. For prebuilt binaries, this also
helps declare which features the binary relies on to ensure the final link
works correctly.</p>
<p>It is recommended to use this variable instead of enabling
<code>-frtti</code> and <code>-fexceptions</code> directly in your
LOCAL_CPPFLAGS definition.</p>
<h3><code>LOCAL_C_INCLUDES</code></h3>
<p>An optional list of paths, relative to the NDK <em>root</em> directory,
which will be appended to the include search path when compiling all sources
(C, C++ and Assembly). For example: </p>
<pre class="fragment">          LOCAL_C_INCLUDES := sources/foo
</pre><p>Or even: </p>
<pre class="fragment">          LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo
</pre><p>These are placed before any corresponding inclusion flag in
LOCAL_CFLAGS / LOCAL_CPPFLAGS</p>
<p>The LOCAL_C_INCLUDES path are also used automatically when launching native
debugging with ndk-gdb.</p>
<h3><code>LOCAL_CFLAGS</code></h3>
<p>An optional set of compiler flags that will be passed when building C
<em>and</em> C++ source files.</p>
<p>This can be useful to specify additional macro definitions or compile
options.</p>
<p><b>IMPORTANT</b>: Try not to change the optimization/debugging level in your
<code>Android.mk</code>, this can be handled automatically for you by
specifying the appropriate information in your Application.mk, and will let the
NDK generate useful data files used during debugging.</p>
<p>NOTE: In android-ndk-1.5_r1, the corresponding flags only applied to C
source files, not C++ ones. This has been corrected to match the full Android
build system behaviour. (You can use LOCAL_CPPFLAGS to specify flags for C++
sources only now).</p>
<p>It is possible to specify additional include paths with LOCAL_CFLAGS +=
-I&lt;path&gt;, however, it is better to use LOCAL_C_INCLUDES for this, since
the paths will then also be used during native debugging with ndk-gdb.</p>
<h3><code>LOCAL_CXXFLAGS</code></h3>
<p>An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete as it
may disappear in future releases of the NDK.</p>
<h3><code>LOCAL_CPPFLAGS</code></h3>
<p>An optional set of compiler flags that will be passed when building C++
source files <em>only</em>. They will appear after the LOCAL_CFLAGS on the
compiler's command-line.</p>
<p>NOTE: In android-ndk-1.5_r1, the corresponding flags applied to both C and
C++ sources. This has been corrected to match the full Android build system.
(You can use LOCAL_CFLAGS to specify flags for both C and C++ sources now).</p>
<h3><code>LOCAL_STATIC_LIBRARIES</code></h3>
<p>The list of static libraries modules that the current module depends on.</p>
<p>If the current module is a shared library or an executable, this will force
these libraries to be linked into the resulting binary.</p>
<p>If the current module is a static library, this simply tells that another
other module that depends on the current one will also depend on the listed
libraries.</p>
<h3><code>LOCAL_SHARED_LIBRARIES</code></h3>
<p>The list of shared libraries <em>modules</em> this module depends on at
runtime. This is necessary at link time and to embed the corresponding
information in the generated file.</p>
<h3><code>LOCAL_WHOLE_STATIC_LIBRARIES</code></h3>
<p>A variant of LOCAL_STATIC_LIBRARIES used to express that the corresponding
library module should be used as "whole archives" to the linker. See the GNU
linker's documentation for the <code>--whole-archive</code> flag.</p>
<p>This is generally useful when there are circular dependencies between
several static libraries. Note that when used to build a shared library, this
will force all object files from your whole static libraries to be added to the
final binary. This is not true when generating executables though.</p>
<h3><code>LOCAL_LDLIBS</code></h3>
<p>The list of additional linker flags to be used when building your shared
library or executable. This is useful to pass the name of specific system
libraries with the '<code>-l</code>' prefix. For example, the following will
tell the linker to generate a module that links to
<code>/system/lib/libz.so</code> at load time: </p>
<pre class="fragment">        LOCAL_LDLIBS := -lz
</pre><p>See <a
href="md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Android NDK
Stable APIs</a> for the list of exposed system libraries you can linked against
with this NDK release.</p>
<p>NOTE: This is ignored for static libraries, and ndk-build will print a
warning if you define it in such a module.</p>
<h3><code>LOCAL_LDFLAGS</code></h3>
<p>The list of other linker flags to be used when building your shared library
or executable. For example, the following will use the <code>ld.bfd</code>
linker on ARM/X86 GCC 4.6+ where <code>ld.gold</code> is the default </p>
<pre class="fragment">        LOCAL_LDFLAGS += -fuse-ld=bfd
</pre><p>NOTE: This is ignored for static libraries, and ndk-build will print a
warning if you define it in such a module.</p>
<h3><code>LOCAL_ALLOW_UNDEFINED_SYMBOLS</code></h3>
<p>By default, any undefined reference encountered when trying to build a
shared library will result in an "undefined symbol" error. This is a great help
to catch bugs in your source code.</p>
<p>However, if for some reason you need to disable this check, set this
variable to '<code>true</code>'. Note that the corresponding shared library may
fail to load at runtime.</p>
<p><em>NOTE</em>: This is ignored for static libraries, and ndk-build will
print a warning if you define it in such a module.</p>
<h3><code>LOCAL_ARM_MODE</code></h3>
<p>By default, ARM target binaries are generated in 'thumb' mode, where each
instruction are 16-bit wide, and linked with /thumb STL libraries. You can
define this variable to '<code>arm</code>' if you want to force the generation
of the module's object files in 'arm' (32-bit instructions) mode. E.g.: </p>
<pre class="fragment">        LOCAL_ARM_MODE := arm
</pre><p>Note that you can also instruct the build system to only build
specific sources in ARM mode by appending an '<code>.arm</code>' suffix to its
source file name. For example, with: </p>
<pre class="fragment">        LOCAL_SRC_FILES := foo.c bar.c.arm
</pre><p>Tells the build system to always compile '<code>bar.c</code>' in ARM
mode, and to build <code>foo.c</code> according to the value of
LOCAL_ARM_MODE.</p>
<p>NOTE: Setting APP_OPTIM to '<code>debug</code>' in your
<code>Application.mk</code> will also force the generation of ARM binaries as
well. This is due to bugs in the toolchain debugger that don't deal too well
with thumb code.</p>
<h3><code>LOCAL_ARM_NEON</code></h3>
<p>Defining this variable to '<code>true</code>' allows the use of ARM Advanced
SIMD (a.k.a. NEON) GCC intrinsics in your C and C++ sources, as well as NEON
instructions in Assembly files.</p>
<p>You should only define it when targeting the '<code>armeabi-v7a</code>' ABI
that corresponds to the ARMv7 instruction set. Note that not all ARMv7 based
CPUs support the NEON instruction set extensions and that you should perform
runtime detection to be able to use this code at runtime safely. To learn more
about this, please read the documentation at <a
href="md_3__key__topics__c_p_u__support__c_p_u-_a_r_m-_n_e_o_n.html">Android
NDK &amp; ARM NEON Instruction Set Extension Support</a> and <a
href="md_3__key__topics__c_p_u__support__c_p_u-_f_e_a_t_u_r_e_s.html">Android
NDK CPU Features detection library</a>.</p>
<p>Alternatively, you can also specify that only specific source files may be
compiled with NEON support by using the '<code>.neon</code>' suffix, as in: </p>
<pre class="fragment">        LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon
</pre><p>In this example, '<code>foo.c</code>' will be compiled in thumb+neon
mode, '<code>bar.c</code>' will be compiled in 'thumb' mode, and
'<code>zoo.c</code>' will be compiled in 'arm+neon' mode.</p>
<p>Note that the '<code>.neon</code>' suffix must appear after the
'<code>.arm</code>' suffix if you use both (i.e. <code>foo.c.arm.neon</code>
works, but not <code>foo.c.neon.arm</code> !)</p>
<h3><code>LOCAL_DISABLE_NO_EXECUTE</code></h3>
<p>Android NDK r4 added support for the "NX bit" security feature. It is
enabled by default, but you can disable it if you <em>really</em> need to by
setting this variable to 'true'.</p>
<p>NOTE: This feature does not modify the ABI and is only enabled on kernels
targeting ARMv6+ CPU devices. Machine code generated with this feature enabled
will run unmodified on devices running earlier CPU architectures.</p>
<p>For more information, see:</p>
<ul>
<li><a href="http://en.wikipedia.org/wiki/NX_bit">Wikipedia: NX bit</a></li>
<li><a href="http://www.gentoo.org/proj/en/hardened/gnu-stack.xml">The GNU
stack kickstart</a></li>
</ul>
<h3><code>LOCAL_DISABLE_RELRO</code></h3>
<p>By default, NDK compiled code is built with read-only relocations and GOT
protection. This instructs the runtime linker to mark certain regions of memory
as being read-only after relocation, making certain security exploits (such as
GOT overwrites) harder to perform.</p>
<p>It is enabled by default, but you can disable it if you <em>really</em> need
to by setting this variable to '<code>true</code>'.</p>
<p>NOTE: These protections are only effective on newer Android devices ("Jelly
Bean" and beyond). The code will still run on older versions (albeit without
memory protections).</p>
<p>For more information, see:</p>
<ul>
<li><a
href="http://isisblogs.poly.edu/2011/06/01/relro-relocation-read-only/">RELRO:
RELocation Read-Only</a></li>
<li><a href="http://www.akkadia.org/drepper/nonselsec.pdf">Security
enhancements in RedHat Enterprise Linux (section 6)</a></li>
</ul>
<h3><code>LOCAL_DISABLE_FORMAT_STRING_CHECKS</code></h3>
<p>By default, NDK compiled code is compiled with format string protection.
This forces a compiler error if a non-constant format string is used in a
printf style function.</p>
<p>It is enabled by default, but you can disable it if you <em>really</em> need
to by setting this variable to '<code>true</code>'.</p>
<h3><code>LOCAL_EXPORT_CFLAGS</code></h3>
<p>Define this variable to record a set of C/C++ compiler flags that will be
added to the LOCAL_CFLAGS definition of any other module that uses this one
with LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES.</p>
<p>For example, consider the module '<code>foo</code>' with the following
definition: </p>
<pre class="fragment">          include $(CLEAR_VARS)
          LOCAL_MODULE := foo
          LOCAL_SRC_FILES := foo/foo.c
          LOCAL_EXPORT_CFLAGS := -DFOO=1
          include $(BUILD_STATIC_LIBRARY)
</pre><p>And another module, named '<code>bar</code>' that depends on it as:
</p>
<pre class="fragment">          include $(CLEAR_VARS)
          LOCAL_MODULE := bar
          LOCAL_SRC_FILES := bar.c
          LOCAL_CFLAGS := -DBAR=2
          LOCAL_STATIC_LIBRARIES := foo
          include $(BUILD_SHARED_LIBRARY)
</pre><p>Then, the flags '<code>-DFOO=1</code> <code>-DBAR=2</code>' will be
passed to the compiler when building <code>bar.c</code>.</p>
<p>Exported flags are prepended to your module's LOCAL_CFLAGS so you can easily
override them. They are also transitive: if '<code>zoo</code>' depends on
'<code>bar</code>' which depends on '<code>foo</code>', then '<code>zoo</code>'
will also inherit all flags exported by '<code>foo</code>'.</p>
<p>Finally, exported flags are <em>not</em> used when building the module that
exports them. In the above example, <code>-DFOO=1</code> would not be passed to
the compiler when building <code>foo/foo.c</code>.</p>
<h3><code>LOCAL_EXPORT_CPPFLAGS</code></h3>
<p>Same as LOCAL_EXPORT_CFLAGS, but for C++ flags only.</p>
<h3><code>LOCAL_EXPORT_C_INCLUDES</code></h3>
<p>Same as LOCAL_EXPORT_CFLAGS, but for C include paths. This can be useful if
'bar.c' wants to include headers that are provided by module 'foo'.</p>
<h3><code>LOCAL_EXPORT_LDFLAGS</code></h3>
<p>Same as LOCAL_EXPORT_CFLAGS, but for linker flags.</p>
<h3><code>LOCAL_EXPORT_LDLIBS</code></h3>
<p>Same as LOCAL_EXPORT_CFLAGS, but for passing the name of specific system
libraries with the '<code>-l</code>' prefix. Note that the imported linker
flags will be appended to your module's LOCAL_LDLIBS though, due to the way
Unix linkers work.</p>
<p>This is typically useful when module '<code>foo</code>' is a static library
and has code that depends on a system library. LOCAL_EXPORT_LDLIBS can then be
used to export the dependency. For example: </p>
<pre class="fragment">          include $(CLEAR_VARS)
          LOCAL_MODULE := foo
          LOCAL_SRC_FILES := foo/foo.c
          LOCAL_EXPORT_LDLIBS := -llog
          include $(BUILD_STATIC_LIBRARY)

          include $(CLEAR_VARS)
          LOCAL_MODULE := bar
          LOCAL_SRC_FILES := bar.c
          LOCAL_STATIC_LIBRARIES := foo
          include $(BUILD_SHARED_LIBRARY)
</pre><p>There, <code>libbar.so</code> will be built with a <code>-llog</code>
at the end of the linker command to indicate that it depends on the system
logging library, because it depends on '<code>foo</code>'.</p>
<h3><code>LOCAL_SHORT_COMMANDS</code></h3>
<p>Set this variable to '<code>true</code>' when your module has a very high
number of sources and/or dependent static or shared libraries. This forces the
build system to use an intermediate list file, and use it with the library
archiver or static linker with the <code>@</code> syntax.</p>
<p>This can be useful on Windows, where the command-line only accepts a maximum
of 8191 characters, which can be too small for complex projects.</p>
<p>This also impacts the compilation of individual source files, placing nearly
all compiler flags inside list files too.</p>
<p>Note that any other value than '<code>true</code>' will revert to the
default behaviour. You can also define APP_SHORT_COMMANDS in your
Application.mk to force this behaviour for all modules in your project.</p>
<p><em>NOTE</em>: We do not recommend enabling this feature by default, since
it makes the build slower.</p>
<h3><code>LOCAL_THIN_ARCHIVE</code></h3>
<p>Set this variable to '<code>true</code>' when building static libraries.
This will generate a 'thin archive', i.e. a library file (e.g.
<code>libfoo.a</code>) which doesn't contain object files, but simply file
paths to the actual objects that it should normally contain.</p>
<p>This is useful to reduce the size of your build output. The drawback is that
such libraries <em>cannot</em> be moved to a different location (all paths
inside them are relative).</p>
<p>Valid values are '<code>true</code>', '<code>false</code>' or empty. A
default value can be set in your Application.mk through APP_THIN_ARCHIVE.</p>
<p><em>NOTE</em>: This is ignored for non-static library modules, or prebuilt
static library ones.</p>
<h3><code>LOCAL_FILTER_ASM</code></h3>
<p>Define this variable to a shell command that will be used to filter the
assembly files from, or generated from, your LOCAL_SRC_FILES.</p>
<p>When it is defined, the following happens:</p>
<ul>
<li>Any C or C++ source file is generated into a temporary assembly file
(instead of being compiled into an object file).</li>
<li>Any temporary assembly file, and any assembly file listed in
LOCAL_SRC_FILES is sent through the LOCAL_FILTER_ASM command to generate
<em>another</em> temporary assembly file.</li>
<li>These filtered assembly files are compiled into object file.</li>
</ul>
<p>In other words, If you have: </p>
<pre class="fragment">          LOCAL_SRC_FILES  := foo.c bar.S
          LOCAL_FILTER_ASM := myasmfilter

        foo.c --1--&gt; $OBJS_DIR/foo.S.original --2--&gt; $OBJS_DIR/foo.S
--3--&gt; $OBJS_DIR/foo.o
        bar.S                                 --2--&gt; $OBJS_DIR/bar.S
--3--&gt; $OBJS_DIR/bar.o
</pre><p>Were "1" corresponds to the compiler, "2" to the filter, and "3" to
the assembler. The filter must be a standalone shell command that takes the
name of the input file as its first argument, and the name of the output file
as the second one, as in: </p>
<pre class="fragment">          myasmfilter $OBJS_DIR/foo.S.original
$OBJS_DIR/foo.S
          myasmfilter bar.S $OBJS_DIR/bar.S</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK
Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
